Contents of progdoc

="3224

@* Introduction.

This program converts a documentation file to a program file, i.e. all files between Ḃ beginprog and Ḃ endprog are copied verbatim. It was written by J. Schrod in September, 1987. This program is written in ẆEB.

The program uses a few features of the local Pascal compiler that may need to be changed in other installations:

30pt to 30pt1)Case statements have a default.

30pt to 30pt2)Input-output routines may need to be adapted for use with a particular character set and/or for printing messages on the user's terminal.

System-dependent portions of MAKEPROG can be identified by looking at the entries for `system dependencies' in the index below. @!@^system dependencies@>

The ``banner line'' defined here should be changed whenever MAKEPROG is modified. The copyright notice must not be changed.

=0 =11 =12

=` =`_

`= `_= =

= `^̂I= = =| =`||

`||=

@print

verbatim=

line= `^̂I=

`||=`
=|gdef|@endverbatim _count _countne

`^̂I=

_mod_viii

Introduction.

WEB systems allow the documentation of programs by supporting the separation in program fragments which can be collected and rearranged afterwards. This allows top-down programming as well as the bottom-up design of programs. Each program fragment can be documented, usually with TEX. A disadvantadge is that WEB actually exists only for a few programming languages (Pascal, C, Modula-2). Besides, building up WEB systems for ``exotic'' programming languages like TEX is very difficult.

This macro package was built to allow good documentation for programs in languages for which WEB doesn't exist. It separates a program text in sections that can be documented. All sections, collected sequentially, will result in the complete program. In every section begin and end of the program part are marked with |
_verbatim (I agree with D. Knuth that |_several_words_long| is much better readable than || and both are better than |@@@s|.) With the at sign we can use the ``private'' Plain macros and with the underscore we can make our own macros more readable. But as we have to restore these category codes at the end of this macro file we store their former values in the control sequences || and ||. This method is better than the usage of a group because not all macros have to be defined global this way.

_verbatim =11 =12

=` =`_

`= `_=

Local Verbatim Formatting.

The main point of every verbatim formatting is the switching of the character codes of all characters that have a special TEX meaning. This can be done with the control sequence || that applies the control sequence || to all special characters. Additionally, every line is regarded as a paragraph without indentation. Between two paragraphs, i.e. between two lines, no extra space is set. Finally all blanks and tabular characters shall be obeyed and the inter word space after sentence terminators shall not be enlarged. The activation of the tabular characters with |`^̂I= | is equivalent to || in plain.tex.

Verbatim texts are set in monospace, we use (like in WEB) the character set with the extended ${\mc ASCII}$ . For LATEX we would have to add here || to all size modifications like ||, ||, etc.

_verbatim `|| printtrue _rest_line =

= `^̂I= =

dd .ne After having saved the old meaning of `' in || and after declaring || as a synonym for the character that has the code of a vertical bar in the actual font, the vertical bar can be made active. Then we call |_verbatim|. But the newline characters shall not be processed, they shall be regarded like blank space. This can be reached by defining |

| as | |.

The next vertical bar in the input closes the group which becomes an (unbreakable) || then. The old meanings of the special characters and of the vertical bar are restored and TEX is in normal (horizontal) mode again.

_verbatim `|| printtrue _rest_line =| =`||

`||=

Program Fragments in Verbatim.

We need macros to format the program fragments without any linebreaking. Such a text area shall start with the macro |
_verbatim `|| printtrue _rest_line | and end with ||. The macro || must stand at the very beginning of a line and must be followed by white space (blank, tab or newline character). After |
_verbatim `|| printtrue _rest_line | as well as after || the rest of the line is ignored.

Two demands must be regarded: There should be no length restrictions for the processed text, and the tabular characters should be expanded so that this macro works on PC's and on VAXes, too.

dd .ne The implementation method is quite simple: We read the next line, test, wether the end is reached (by comparing with ||) and otherwise set the character actually read. Every character is inspected and tabular characters are expanded.

Wether a line is set or wether the end of the processed area is reached is indicated by the switch |@print|. At the beginning of the |
_verbatim `|| printtrue _rest_line | macro most settings are done with |_verbatim| (the vertical bar must be handled separately) and the rest of the line is ignored. As everything is done within a group, the end of the verbatim text can be processed by simply closing this group.

For the user it looks as if || terminates the processing, but it just serves for the identification of the end, the true processing is done with the internal macro |verbatim|.

_verbatim `|| printtrue _rest_line @print

verbatim=

dd .ne The first line is ignored, all the other lines are identified with |_next_line| and processed with |_set|. This separation in identification and processing allows that the line end character is active in the definition only for a short time.

When a line is to be formatted, we first check with |_̌print| wether it contains ||, otherwise it is printed with |_char|. The printing must be done for every character individually because we want to check for tabular characters; the exact algorithm is described below. Here we just have to note that |_char| is used with two parameters of which the second one is finished with the token |line|. The first parameter is the first character of the line, the second parameter is the rest of the line. If the line is empty, the argument of |_set| is empty, too; so the activation of |_char| must be finished with two |line|. Then the first |line| is the first argument for |_char| and the second argument is empty. But if the line did contain something, the second |line| is evaluated, for this case it is defined as ||.

At last we call |_next_line| again to format the next line. If the end is reached, i.e. if a line with || was found, |_next_line| is redefined as ||. This can be done because the original meaning is restored while closing the group with |verbatim|.

_verbatim `|| printtrue _rest_line

line=

dd .ne Before we look at the problem of formatting a line, we declare |_̌print| that checks the end of the verbatim mode. We have to do two things: we must split everything in front of the first blank or tabular character and compare for identity with ||. The splitting is easy because the line which is our first argument contains blanks and tabulators as active characters. First we call |_at_tab| that demands a tabular character as separator for its two pramenters so that everything in the line in front of the first tabulator is part of the first parameter. If there is no tabular character in the line, we append one so that the second parameter is empty. The same trick is used to separate the part in front of the first blank character from the resulting first part.

The check is done with |_check|. We use a separate macro here so that we can indent it (in the following definition blanks are active!)

_verbatim `|| printtrue _rest_line `^̂I=

dd .ne |_check| compares the line with a sample line that is available in |endverbatim|. During the definition of |endverbatim| it must be cared for that the escape character `|||' is a printable character: A comparison with || demands identical category codes. As a temporary escape character we use the vertical bar.

_verbatim `|| printtrue _rest_line

`||=`
=|gdef|@endverbatim

dd .ne Now we can set a line: we start with the first character, followed by the rest of the line. Each character is counted in |_count|. At the beginning of a line |_count| is 1, this is reset at the end of the line.

_verbatim `|| printtrue _rest_line _count _countne

_verbatim `|| printtrue _rest_line `^̂I=

dd .ne If we want to fill the line with blank spaces up to the next column with a number that can be divided by 8, we must be able to compute the column number modulo 8, but TEX has no modulo operator. So we define the macro |_viii| that computes its argument modulo 8 and returns the result in the counter |_mod_viii|. For the computation we need the temporary counter |@|.

_verbatim `|| printtrue _rest_line _mod_viii

dd .ne Now we can declare |_tab|. We must remember that |_count| was incremented already, if we set only one blank character the counter keeps untouched.

_verbatim for the next line.

Inside the || part of || |_char| should not be used directly because this costs too much storage of TEX. Instead we set a control sequence || that is processed afterwards, depending on the result of the comparison. If there is still something to set, we use |_char| again, otherwise a syntactically similar macro that expands to ||.

_verbatim `|| printtrue _rest_line

Document Structuring.

The layout of the document shall be like in WEB. This can be done easily in Plain. If LATEX shall be used for the document preparation, this part of the macro must be eliminated. It will also be better to include the program parts LATEX-like as an environment between |
$\begin{prog}\vert and \vert\end{prog}$
| and to define control sequences || and || for the switch of the special meaning of the vertical bar (`') (for the tabular environment!)

All sections are enumerated, the number of the next section is stored in the counter ||. We differenciate between main sections which start a group of sections and between normal sections within a group.

_verbatim `|| printtrue _rest_line =ne

dd .ne The main sections are started with the macro || that has one parameter, the title of the section group. This parameter must be terminated by a dot. We start a new page, typeset the title in bold face and separate it from the section text with a |

|. This text, the documentation part of the section, is formatted without paragraph indentation.

The deletion of the paragraph indentation is done with ||. We do not care if || is used for something else and delete it after usage.

Here the title, the section and the page number should be written to an auxiliary file so that a table of contents could be created at the end of the run (at ||), and the dealing with || should not be so cruel.

_verbatim `|| printtrue _rest_line

dd .ne Normal sections are started with |
dd .ne |. This macro has no parameter. Between two paragraphs we set 2 pica space (if possible) and prefer the page breaking. Between the section number and the text one quad of space is set.

The page break manipulation could be more sophisticated.

_verbatim `|| printtrue _rest_line

dd .ne We are finished and just have to restore the category codes.

_verbatim `|| printtrue _rest_line `= `_=